Automation

BindAI Automation provides a foundation for defining executable automations, tracking individual runs, responding to events, and executing automation definitions synchronously or in the background. The current automation package provides:

Automation definitions
Automation run lifecycle and execution state
Automation run history
Event triggers
Trigger management and registry operations
Synchronous automation execution
Background execution using an in-process thread pool
In-memory state and history implementations

The architecture is intentionally lightweight. Persistent storage, distributed workers, advanced event routing, and additional trigger types can be introduced separately as the framework evolves. Important: The current implementation is not a complete distributed automation platform. In particular, its default state and history stores are in-memory, and background execution is tied to the application process.

Automation Architecture

The automation package separates automation definitions, execution state, historical records, event triggers, and background execution.

AutomationDefinition
        |
        v
   AutomationRun
        |
        +----------------------+
        |                      |
        v                      v
AutomationStateStore   AutomationRunHistory
        |                      |
        v                      v
 Current Run State       Historical Runs

Event-driven automation uses BindAI’s event system:

Event Source
     |
     v
  EventBus
     |
     v
 EventTrigger
     |
     v
Application Target

Background execution is provided by AutomationWorker:

AutomationDefinition
        |
        v
  AutomationWorker
        |
        v
   AutomationRun
        |
        +----------------------+
        |                      |
        v                      v
AutomationStateStore   AutomationRunHistory

These components have separate responsibilities:

AutomationDefinition describes an executable automation.
AutomationRun represents one execution and its lifecycle state.
AutomationStateStore stores the current state of a run.
AutomationRunHistory provides an interface for recording and retrieving historical runs.
EventTrigger connects an event subscription to application-defined callable logic.
AutomationWorker executes automation definitions synchronously or in the background.

Event triggers and background workers are separate mechanisms. An event trigger does not automatically create a background job, and an automation definition does not need to be invoked through an event trigger.

Automation Package

The automation package is provided by bindai-automation and imported as bindai_automation.

import bindai_automation

The public API used in this guide includes:

from bindai_automation import (
    AutomationDefinition,
    AutomationRun,
    AutomationRunHistory,
    AutomationStateStore,
    AutomationWorker,
    MemoryAutomationRunHistory,
    MemoryAutomationStateStore,
    Trigger,
    EventTrigger,
    TriggerRegistry,
)

Use the package’s actual exported interfaces when building integrations. Do not assume that a future capability is available unless it is implemented and exported by the installed version.

Automation Definitions

AutomationDefinition describes an automation and the executable target it invokes.

from bindai_automation import AutomationDefinition

automation = AutomationDefinition(
    name="my-automation",
    target=my_executable,
)

A definition provides:

id — the automation definition identifier.
name — a human-readable automation name.
version — the definition version, starting at 1.
target — the executable target associated with the definition.
metadata — optional application-defined metadata.

Definitions can be cloned to create a new version:

version_2 = automation.clone()

assert version_2.version == 2
assert automation.version == 1

The automation definition describes what is configured to run. A worker or application code determines when and how execution is initiated. Cloning a definition should not be confused with persisting a version history in a database. Versioning the definition object does not, by itself, provide durable storage or deployment management.

Automation Runs

AutomationRun represents one execution of an automation definition.

from bindai_automation import AutomationRun

run = AutomationRun(
    definition_id=automation.id,
    definition_version=automation.version,
    input={"message": "hello"},
)

run.start()

# Execute the automation target here.

run.complete(output={"result": "done"})

An automation run provides:

id — the unique execution identifier.
definition_id — the automation definition identifier.
definition_version — the definition version associated with the run.
status — the execution state.
input — input data stored on the run.
output — execution output when available.
error — failure information when execution fails.
created_at — the run creation timestamp.
started_at — the execution start timestamp.
completed_at — the execution completion timestamp.

The run lifecycle methods include:

run.start()

run.complete(output={"result": "done"})

run.fail("execution failed")

Runs begin in the pending state. During execution, the worker moves a run to running, then to completed or failed, depending on the result. Run timestamps are UTC-aware. The run object represents execution state independently from the automation definition. Creating a run does not automatically execute the definition or persist the run in a store.

Automation State

AutomationStateStore defines the storage contract for the current state of automation runs. A custom implementation can provide application-specific storage:

from bindai_automation import AutomationStateStore


class CustomAutomationStateStore(AutomationStateStore):
    def save(self, run):
        ...

    def load(self, run_id):
        ...

    def delete(self, run_id):
        ...

Implement the methods required by the actual abstract interface in the installed package. The state store is separate from AutomationRun. This allows current run state to be managed independently of the run model and supports alternative storage implementations. The state store represents the current execution state of a run. It does not, by itself, provide a permanent audit trail.

In-Memory State Store

MemoryAutomationStateStore provides an in-memory implementation of the automation state store.

from bindai_automation import MemoryAutomationStateStore

store = MemoryAutomationStateStore()

store.save(run)

loaded = store.load(run.id)

assert loaded is run

The in-memory state store retains the stored run object. In the current implementation, loading a run returns the same object reference rather than an independent snapshot. Runs can also be removed:

store.delete(run.id)

assert store.load(run.id) is None

MemoryAutomationStateStore is the default state store used by AutomationWorker when no custom state store is supplied. Because it is in-memory, its state is process-local and is not durable across application restarts. Applications requiring durable state can provide another AutomationStateStore implementation. The interface alone does not supply a database backend or guarantee persistence.

Automation Run History

AutomationRunHistory defines the history contract for recording and retrieving automation runs. A custom implementation can provide application-specific history storage:

from bindai_automation import AutomationRunHistory


class CustomAutomationRunHistory(AutomationRunHistory):
    def record(self, run):
        ...

    def get(self, run_id):
        ...

    def list(self):
        ...

Implement the methods required by the actual abstract interface in the installed package. Run history is separate from AutomationStateStore. The state store answers:

What is the current execution state of this run?

Run history answers:

Which recorded run can be retrieved from the history implementation?

The history contract provides:

record(run) — record a run.
get(run_id) — retrieve a recorded run by ID.
list() — retrieve recorded runs.

This separation allows current execution state and historical records to evolve independently. The existence of a history interface does not imply that historical records are stored permanently. Durability depends on the implementation being used.

In-Memory Run History

MemoryAutomationRunHistory provides an in-memory implementation of AutomationRunHistory.

from bindai_automation import (
    AutomationRun,
    MemoryAutomationRunHistory,
)

history = MemoryAutomationRunHistory()

run = AutomationRun(
    definition_id=automation.id,
    definition_version=automation.version,
)

run.start()
run.complete(output={"result": "done"})

history.record(run)

stored = history.get(run.id)

assert stored is not None
assert stored.id == run.id

The current in-memory history implementation records snapshots of runs. Later changes to the original run do not change the recorded snapshot.

run.output = {"result": "changed"}

stored = history.get(run.id)

assert stored is not None
assert stored.output == {"result": "done"}

MemoryAutomationRunHistory is the default history implementation used by AutomationWorker when no custom history implementation is supplied. History records remain in memory and do not survive application restarts. A custom implementation is required for durable history.

Automation Worker

AutomationWorker executes automation definitions and manages the lifecycle of their AutomationRun objects. Its current capabilities include:

Synchronous execution
Background execution
Configurable state storage
Configurable run history
Configurable maximum worker count
Worker shutdown
Context-manager usage

Example:

from bindai_automation import AutomationWorker

worker = AutomationWorker()

run = worker.run(
    automation,
    input={"message": "hello"},
)

future = worker.submit(
    automation,
    input={"message": "hello"},
)

background_run = future.result()

worker.shutdown()

The worker is responsible for:

Creating an AutomationRun.
Saving the initial run state.
Starting the run.
Executing the automation definition.
Completing or failing the run.
Saving the final run state.
Recording the run in history.

Input behavior: The worker stores the supplied input on the run, but the current execution path calls definition.run() without passing that input as an argument. Do not assume that the input is automatically delivered to the automation target. The worker also does not provide automatic retries or durable background job delivery.

Worker Configuration

AutomationWorker accepts optional state and history implementations, along with a configurable thread-pool size.

worker = AutomationWorker(
    state_store=custom_state_store,
    history=custom_history,
    max_workers=4,
)

The defaults are:

MemoryAutomationStateStore
MemoryAutomationRunHistory
max_workers=4

The worker rejects an invalid worker count:

worker = AutomationWorker(max_workers=0)

This raises a ValueError indicating that max_workers must be at least 1. Custom state and history implementations can be supplied when applications need different persistence behavior. Their durability, concurrency handling, and failure guarantees depend on the implementations themselves.

Synchronous Execution

The worker supports synchronous execution through run().

worker = AutomationWorker()

run = worker.run(
    automation,
    input={"message": "hello"},
)

The call executes the automation in the calling thread and returns an AutomationRun after execution completes or fails. Conceptually:

Application
    |
    v
worker.run()
    |
    v
AutomationDefinition
    |
    v
AutomationRun
    |
    v
Completed / Failed

Synchronous execution does not submit the work to the worker’s background thread pool. The returned run contains the execution state and result or error recorded by the worker. As with background execution, the supplied input is stored on the run but is not automatically passed into definition.run().

Background Submission

The worker supports background execution through submit().

worker = AutomationWorker()

future = worker.submit(
    automation,
    input={"message": "hello"},
)

run = future.result()

worker.shutdown()

submit() returns a Future whose result is an AutomationRun. The future resolves when the submitted worker task finishes. The run records whether the automation completed or failed. The worker uses an in-process thread pool for background execution. A future is not a persistent job record and does not guarantee that work will survive process termination. Call shutdown() when the worker is no longer required.

Submit With Run

Applications that need a run object and identifier immediately can use submit_with_run().

worker = AutomationWorker()

run, future = worker.submit_with_run(
    automation,
    input={"message": "hello"},
)

print(run.id)

completed_run = future.result()

worker.shutdown()

The important difference is that submit_with_run() returns the AutomationRun and its Future immediately while execution proceeds in the background. The worker saves the initial run state before submitting background execution. This allows an application to obtain the run identifier before execution has completed. Conceptually:

submit_with_run()
       |
       +---- Create AutomationRun
       |
       +---- Save initial state
       |
       +---- Submit background execution
       |
       +---- Return run + Future

The initial state is only as durable as the configured state store. With the default in-memory implementation, it is process-local.

Background Worker Model

In BindAI v0.1, AutomationWorker uses an in-process ThreadPoolExecutor. Conceptually:

BindAI Application Process
|
+-- AutomationWorker
       |
       +-- Worker Thread
       +-- Worker Thread
       +-- Worker Thread
       +-- Worker Thread

The default maximum worker count is 4. Applications can configure it:

worker = AutomationWorker(max_workers=8)

The worker runs inside the application process. It is not a separate worker service and does not use a distributed queue. The configured worker count limits the thread pool; it does not configure multiple machines, provide autoscaling, or coordinate workers across application instances.

Worker Lifecycle

Workers should be shut down when they are no longer required:

worker.shutdown()

The shutdown method supports options corresponding to the underlying executor:

worker.shutdown(
    wait=True,
    cancel_futures=False,
)

wait controls whether shutdown waits for running work to finish.
cancel_futures controls whether pending futures are cancelled when supported by the underlying executor.

Cancellation of pending futures does not forcibly interrupt a task that is already running. For long-running applications, manage worker lifetime explicitly and account for the behavior of in-process background work during application shutdown.

Context Manager

AutomationWorker can also be used as a context manager:

with AutomationWorker() as worker:
    run = worker.run(automation)

Leaving the context shuts down the worker. This provides a convenient lifecycle for applications that create a worker for a bounded period. As with explicit shutdown, context-manager cleanup does not make background jobs durable across process termination.

Run Execution

When the worker executes an automation, its lifecycle follows this general sequence:

Create AutomationRun
        |
        v
Save Initial State
        |
        v
Start Run
        |
        v
Execute Definition
        |
        +----------+
        |          |
        v          v
     Success     Failure
        |          |
        v          v
    Complete      Fail
        |          |
        +-----+----+
              |
              v
       Save Final State
              |
              v
        Record History

The worker calls the automation definition and checks the execution result. Successful execution completes the run with its output; an unsuccessful result or an exception causes the run to be marked as failed. Exceptions raised during definition execution are caught by the worker, and the failure is recorded on the run. This does not constitute a general retry or recovery system. The state and history operations are subject to the behavior and limitations of their configured implementations.

Automation Input

Automation runs accept an optional input value:

run = AutomationRun(
    definition_id=automation.id,
    definition_version=automation.version,
    input={
        "message": "hello",
    },
)

The worker also accepts input:

future = worker.submit(
    automation,
    input={
        "message": "hello",
    },
)

The input is stored on the resulting AutomationRun. Current implementation note: The worker’s execution path calls definition.run() without passing the stored AutomationRun.input value as an argument. Therefore, applications should not assume that the worker automatically injects input into the automation target. If execution logic needs that data, the application must arrange an explicit supported path for providing it. Input propagation can be expanded in a future execution model.

Automation Output

A successful definition execution produces a result. The worker checks the result’s success state and uses the result output to complete the run. Conceptually:

AutomationDefinition.run()
        |
        v
 Execution Result
        |
        +---- success
        |       |
        |       v
        |   run.complete(output)
        |
        +---- failure
                |
                v
            run.fail(error)

The exact result type and its success and output fields depend on the current automation definition implementation. Applications should use the actual result contract rather than assuming that every executable target returns an arbitrary dictionary or that all result types share the same fields.

Automation Failures

If automation execution raises an exception, the worker catches it and marks the run as failed.

AutomationDefinition
        |
        v
    Exception
        |
        v
 AutomationRun.fail(...)
        |
        v
    Save State
        |
        v
   Record History

Applications can inspect the run’s status and error fields after execution. The worker’s exception handling does not automatically retry failed runs. It also does not guarantee that every possible storage or process-level failure can be recovered from. For critical workloads, consider persistence, idempotency, external side effects, and explicit failure-recovery behavior.

Worker and Event Triggers

AutomationWorker and EventTrigger solve different problems. EventTrigger connects an event subscription to application logic:

EventBus
   |
   v
EventTrigger
   |
   v
Target Callable

AutomationWorker executes an AutomationDefinition:

AutomationDefinition
   |
   v
AutomationWorker
   |
   v
AutomationRun

An application can combine the two by invoking application logic from an event target that submits an automation to a worker. Conceptually:

EventBus
   |
   v
EventTrigger
   |
   v
Application Target
   |
   v
AutomationWorker
   |
   v
AutomationDefinition

This is an application-level composition, not an automatic behavior of every trigger. The automation package does not require every event trigger to use a background worker.

Trigger

Trigger is the base abstraction for automation triggers.

from bindai_automation import Trigger

The trigger interface provides lifecycle operations such as:

trigger.enable()

trigger.disable()

trigger.attach()

trigger.detach()

The trigger abstraction includes an enabled state and operations for enabling, disabling, attaching, and detaching a trigger. Concrete trigger implementations determine how subscriptions are established and how matching events are handled. Attaching a trigger and enabling a trigger represent different lifecycle concerns. Consult the concrete implementation when relying on the exact behavior of disabled or detached triggers.

Enabling and Disabling Triggers

Triggers expose methods for enabling and disabling their behavior:

trigger.disable()

A trigger can later be enabled again:

trigger.enable()

The enabled state is distinct from the act of attaching or detaching a trigger. Do not assume that enabling a trigger automatically attaches it, or that disabling it removes its event subscription, unless the concrete implementation explicitly provides that behavior. Use the lifecycle methods deliberately when managing event subscriptions in long-running applications.

Event Triggers

EventTrigger connects a BindAI EventBus subscription to a target callable.

from bindai_automation import EventTrigger

A trigger is configured with:

An event bus
An event name
A target callable

For example:

trigger = EventTrigger(
    bus=context.events,
    event_name="tool.executed",
    target=handle_event,
)

A compatible target callable can process the matching event:

def handle_event(event):
    print(event)

The event names that can be observed depend on the events published by the connected BindAI runtime and event source. An event name used in an example should not be interpreted as a guarantee that every runtime operation publishes that event.

BindAI Event System

BindAI’s execution context provides access to an EventBus through:

context.events

The event bus is used by runtime components to publish execution events. Depending on the components and operations in use, event categories may include:

Application lifecycle
Agent execution
Workflow execution
Workflow nodes
Human tasks
Model requests and responses
Tool execution
Memory operations
MCP connection lifecycle

The precise event names and payloads depend on the event publishers implemented by the relevant components. An EventTrigger can subscribe to a named event on an event bus and invoke its target when a matching event is delivered. Do not assume that every category listed above is emitted in every execution path. Consult the event definitions and publishers for the runtime version being used.

Attaching an Event Trigger

An EventTrigger must be attached before its subscription can receive matching events.

trigger.attach()

The general flow is:

EventBus
   |
   | matching event
   v
EventTrigger
   |
   v
target(event)

Attaching establishes the trigger’s event subscription according to its implementation. Repeated attachment should be treated according to the concrete trigger’s lifecycle contract. Where duplicate-subscription protection is implemented, repeated calls should not create duplicate subscriptions; do not generalize that guarantee to other trigger types without verifying their behavior.

Detaching an Event Trigger

An attached trigger can be detached from its event source:

trigger.detach()

Detaching removes the subscription managed by the trigger. After detachment, that subscription no longer delivers events to the trigger. The behavior of repeated calls to detach() depends on the implementation’s lifecycle handling. For long-running applications, detach triggers when their subscriptions are no longer needed. A typical lifecycle is:

trigger.attach()

# The trigger is attached to its event source.

trigger.detach()

Event Matching

EventTrigger subscribes to a specific event name. For example:

trigger = EventTrigger(
    bus=context.events,
    event_name="tool.executed",
    target=handle_event,
)

The underlying event bus determines which events match the subscription. When a matching event is delivered to the trigger, the event object is passed to the target callable. The event bus and publisher determine the event payload. Applications should validate and handle the payload according to the event contract they use.

Event-Driven Automation

A simple event-driven automation flow is:

Execution Component
        |
        v
     EventBus
        |
        v
   EventTrigger
        |
        v
 Application Target

For example:

def handle_tool_event(event):
    print("Tool event received:", event)


trigger = EventTrigger(
    bus=context.events,
    event_name="tool.executed",
    target=handle_tool_event,
)

trigger.attach()

This example assumes that the relevant execution context publishes the named event. The trigger can react to events without requiring changes to the tool execution implementation. However, event delivery and target execution follow the behavior of the existing event system; attaching a trigger does not by itself create a durable background job.

Targets

An EventTrigger accepts a callable target.

def handle_event(event):
    ...

The target contains the application-specific logic to run when the trigger receives an event. For example:

def notify(event):
    print("Automation triggered")

Then:

trigger = EventTrigger(
    bus=context.events,
    event_name="tool.executed",
    target=notify,
)

The automation package does not impose a separate higher-level target type. A function, callable object, or other compatible callable can be used. Targets are application code and are responsible for handling event data, validation, authorization, external side effects, and any additional execution requirements.

Trigger State

Trigger attachment and enabled state are separate lifecycle concepts. Conceptually:

Trigger
   |
   +---- Attachment / Subscription
   |
   +---- Enabled State

An application can attach a trigger and then change its enabled state:

trigger.attach()

trigger.disable()

trigger.enable()

trigger.detach()

The precise interaction between these operations is determined by the trigger implementation. In particular, do not assume that disabling always removes a subscription or that enabling always creates one. Detaching a trigger is the operation intended to remove its subscription.

Trigger Registry

TriggerRegistry provides a registry for trigger instances.

from bindai_automation import TriggerRegistry

registry = TriggerRegistry()

A trigger can be registered under a key:

registry.register(
    "tool-events",
    trigger,
)

It can then be retrieved:

trigger = registry.get("tool-events")

A non-throwing lookup is also available:

trigger = registry.get_or_none("tool-events")

The registry helps application code organize and look up trigger instances. It is not, by itself, a trigger scheduler or persistent configuration store.

Registry Operations

TriggerRegistry provides operations for managing registered triggers.

registry.register("tool-events", trigger)

registry.get("tool-events")

registry.get_or_none("tool-events")

registry.contains("tool-events")

registry.remove("tool-events")

registry.clear()

The registry also exposes collection views:

registry.keys()

registry.values()

registry.items()

and supports:

len(registry)

The registry is useful when an application needs to manage multiple triggers dynamically. Registering a trigger does not automatically attach it to its event source. Registry membership and event subscription are separate concerns.

Automation and Agents

Agents can participate in event-driven application behavior when their runtime operations publish events to a BindAI event bus. A conceptual flow is:

Agent Execution
      |
      v
ExecutionContext
      |
      v
EventBus
      |
      v
EventTrigger
      |
      v
Application Action

This lets application code respond to relevant execution events without embedding all automation behavior directly inside the agent implementation. The event bus belongs to the execution context used by the relevant runtime operation. Applications should use the event bus available through that context rather than assuming that every agent object exposes a separate event bus. The availability of a particular event depends on the event publishers implemented by the relevant runtime path.

Automation and Workflows

Automation can be combined with workflows through application-defined callable targets. A conceptual flow is:

Event
  |
  v
EventTrigger
  |
  v
Application Target
  |
  v
Workflow / Executable

The current automation package does not define a dedicated universal workflow-trigger API. Instead, the trigger target is a generic callable. Application code can use that callable to invoke the workflow or executable behavior appropriate for the application. Workflow execution, event delivery, and background submission should be treated as separate operations unless an integration explicitly combines them.

Automation and Connections

Automation can be combined with BindAI Connections through application code. For example:

Event
 |
 v
EventTrigger
 |
 v
Application Action
 |
 v
Connection
 |
 v
External Service

An application can use a trigger target to send information to an external service through an appropriate connection. The automation package does not directly manage Connections. Connection setup, authentication, authorization, request handling, and external-service error handling remain the responsibility of the application or integration layer.

Automation and the REST API

BindAI’s REST API exposes background automation runs through these endpoints:

POST /api/v1/runs

GET /api/v1/runs/{run_id}

The API submits an existing automation definition to the configured AutomationWorker. Conceptually:

HTTP Client
    |
    v
BindAI API
    |
    v
AutomationWorker
    |
    v
AutomationDefinition
    |
    v
AutomationRun

The submission endpoint responds with HTTP 202 Accepted and a run identifier. Clients can use the run identifier to request the run’s status and result information. The API requires a valid API key when BINDAI_API_KEY is configured. If the server-side key is missing, the authentication dependency raises a configuration error rather than treating the request as an ordinary invalid-key request. See Background Runs for the HTTP API details.

Automation State and the REST API

The REST API can expose the state of a background automation run. The response can include:

Run ID
Automation definition ID
Definition version
Status
Input
Output
Error
Creation timestamp
Start timestamp
Completion timestamp

This provides a lightweight execution-status API for v0.1. The API looks up runs through the configured worker’s state store and, if necessary, its run history. With the default in-memory implementations, this data is process-local. It should not be treated as a shared or durable run-state database. The API’s ability to retrieve a run depends on the run being available through those configured stores.

Background Runs and Process Lifetime

The current background worker is process-local. Conceptually:

Application Process
|
+-- BindAI API
|
+-- AutomationWorker
      |
      +-- Background Run

If the application process stops, in-process background work can be interrupted. Pending futures and run records are not automatically transferred to another process or machine. The default in-memory state and history are also lost when the process terminates. Applications requiring durable execution should use appropriate persistent storage and a background execution system designed for their reliability requirements.

Horizontal Scaling

Running multiple API instances does not automatically create one shared background worker pool. For example:

Load Balancer
      |
      +---- API Instance A
      |        |
      |        +---- AutomationWorker A
      |
      +---- API Instance B
               |
               +---- AutomationWorker B

The workers operate independently. The current v0.1 worker does not provide cross-process coordination or a distributed queue. With in-memory state and history, each instance also has its own local records. A run created by one instance might not be available when a subsequent request is handled by another instance. Applications requiring coordinated background execution should use an external queue or job system and appropriately shared storage until a dedicated distributed execution architecture is available.

Persistent State and History

The default state and history implementations are in-memory:

AutomationWorker
      |
      +---- MemoryAutomationStateStore
      |
      +---- MemoryAutomationRunHistory

Applications can provide custom implementations:

worker = AutomationWorker(
    state_store=custom_state_store,
    history=custom_history,
)

This allows applications to introduce alternative storage without changing the basic AutomationRun abstraction. The default in-memory implementations are process-local and do not provide durable persistence across application restarts. Persistent behavior, consistency guarantees, and concurrent-access behavior depend on the custom implementations supplied by the application.

Error Handling

The underlying BindAI EventBus and the automation worker have different error-handling responsibilities. The current event system handles exceptions raised by event handlers according to its event-dispatch implementation. Applications should consult that implementation when relying on handler isolation, logging, or continued delivery to other handlers. EventTrigger does not provide a separate universal retry or failure-recovery system. For background automation execution, AutomationWorker catches exceptions raised during definition execution and records the resulting failure on the AutomationRun. Applications requiring additional retries, persistence, dead-letter handling, or failure recovery must implement those concerns at the appropriate automation, workflow, or infrastructure layer.

Synchronous Event Processing

The current core EventBus processes event handlers synchronously. Conceptually:

publish(event)
      |
      v
 EventTrigger
      |
      v
 target(event)

An EventTrigger does not automatically create a background worker or persistent job. If event handling requires explicit background execution, the application can invoke an AutomationWorker or another execution mechanism from the target. For example, a target can submit an automation definition to a worker when that is appropriate for the application’s design. This keeps event delivery and background execution as separate responsibilities. Because event processing is synchronous, a slow target can affect the time taken by the event-dispatch operation.

Trigger Lifecycle

A typical trigger lifecycle is:

Create
  |
  v
Configure
  |
  v
Attach
  |
  v
Enable / Process Matching Events
  |
  +---- Disable
  |       |
  |       v
  |    Disabled
  |       |
  |       v
  |     Enable
  |       |
  +-------+
  |
  v
Detach

The exact effect of enabling and disabling depends on the trigger implementation. Attachment and detachment manage the event subscription, while enabled state controls the trigger’s enabled/disabled lifecycle. For long-running applications, detach triggers when their subscriptions are no longer required.

Testing Automation

Automation components should be tested independently from external services they may eventually control. Useful tests include:

Trigger construction
Enable/disable behavior
Attach behavior
Detach behavior
Event matching
Target invocation
Duplicate-attachment handling, where implemented
Registry operations
Handler failure behavior
Automation run lifecycle
State-store operations
Run-history recording
Run-history retrieval
Run-history snapshot isolation
Synchronous worker execution
Background worker execution
Background worker state updates
Background worker run-history recording
Worker shutdown behavior
Worker configuration validation

Event buses can be used with test events and test callables so that automation behavior can be verified without contacting external services. Tests should also cover the input-propagation limitation: submitting input to the worker stores it on the run but does not automatically pass it to definition.run() in the current implementation. For tests involving asynchronous execution, wait for the returned future before asserting the final run state or history.

Security Considerations

Automation can cause actions to occur automatically in response to events. Applications should consider:

Which events are allowed to trigger automation
Which targets can be invoked
Whether a target performs external side effects
Credential and secret handling
Authorization boundaries
Input validation
Audit requirements
Duplicate event handling and idempotency
Failure behavior when external services are unavailable

Automation targets should not expose secrets or credentials through event payloads unnecessarily. State-changing automation should apply the validation and authorization controls appropriate to the operation. A trigger subscription or registry entry is not, by itself, an authorization mechanism. When external side effects are involved, consider whether the operation can safely be repeated after a failure or duplicate event.

Production Considerations

The in-process worker model is a lightweight execution mechanism, not a guarantee of durable job processing. Production deployments should consider:

Application and container restarts
Long-running automation
Worker capacity
External-service failures
Retry behavior
Idempotency
Monitoring and observability
Run-state persistence
Failure recovery
Shutdown behavior
Cross-instance coordination

The default state store and history are in-memory. Background execution uses an in-process thread pool, and the worker does not automatically retry failed jobs or transfer unfinished work to another process. For durable distributed execution, an external queue, persistent state storage, and an appropriate worker architecture may be required.

Current Scope

The current BindAI Automation package provides the following capabilities.

Automation

AutomationDefinition
AutomationRun
AutomationStateStore
MemoryAutomationStateStore
AutomationRunHistory
MemoryAutomationRunHistory
AutomationWorker

Worker execution

Synchronous execution
Background execution
submit_with_run()
Configurable thread-pool size
Worker shutdown
Context-manager support
Run-state updates
Run-history recording

Event integration

Trigger
EventTrigger
BindAI EventBus integration
Named event subscriptions
Event-driven callable targets
Enable/disable lifecycle
Attach/detach lifecycle

Registry support

TriggerRegistry
Trigger registration
Trigger lookup
Trigger removal
Trigger enumeration
Registry clearing

REST API integration

The BindAI API also provides:

Background run submission
Run identifiers
Run status lookup
Run output
Run error information

The package provides a foundation for stateful and event-driven automation without attempting to implement a complete distributed automation platform.

Current Limitations

The current v0.1 automation implementation does not provide the following as built-in capabilities:

Distributed job queues
Durable distributed workers
Cross-process worker coordination
Automatic worker failover
Built-in worker autoscaling
Database-backed state by default
Database-backed history by default
Kubernetes-native job execution
A hosted automation dashboard
Advanced event-routing infrastructure
Automatic delivery of AutomationRun.input to AutomationDefinition.run()
Automatic retries for failed background automation runs
Guaranteed completion of in-process jobs after application termination

These capabilities are outside the current implementation’s scope. The current worker is process-local and uses an in-process thread pool. The default state and history implementations are also process-local.

Future Automation Capabilities

Future automation development could include:

Advanced event routing
Additional trigger types
Persistent database-backed automation state
Persistent database-backed run history
Distributed queue-based execution
Coordinated worker processes
More advanced scheduling and execution policies
Broader automation orchestration
Monitoring and operational tooling
Improved automation input and context propagation
More comprehensive retry and recovery policies

These capabilities should build on the current automation definition, run, state, history, trigger, event, and worker foundations. They should not be assumed to exist until implemented and documented for a specific release.

Design Principles

BindAI Automation follows several design principles:

Keep triggers small and composable.
Reuse the existing event system.
Separate event detection from automation actions.
Make trigger lifecycle explicit.
Keep background execution explicit.
Keep external-service concerns outside the trigger abstraction.
Allow additional trigger types without unnecessarily changing the core event infrastructure.
Keep automation state separate from event subscriptions.
Keep current execution state separate from historical run records.
Keep the history interface small so alternative backends can be introduced.
Use AutomationWorker for explicit synchronous and background execution.
Avoid implying distributed execution where only process-local execution exists.
Document automation input behavior according to the actual execution path.
Make durability and failure-recovery guarantees dependent on the configured infrastructure.

API Accuracy

This guide describes the APIs implemented by the current bindai-automation package and its integration with BindAI’s event system. The public automation API used here includes:

AutomationDefinition(...)

AutomationRun(...)

AutomationStateStore(...)

MemoryAutomationStateStore(...)

AutomationRunHistory(...)

MemoryAutomationRunHistory(...)

AutomationWorker(...)

Trigger(...)

EventTrigger(...)

TriggerRegistry(...)

AutomationWorker provides:

worker.run(...)

worker.submit(...)

worker.submit_with_run(...)

worker.shutdown(...)

It also supports context-manager usage:

with AutomationWorker() as worker:
    ...

The worker uses an in-process ThreadPoolExecutor. The default state store is MemoryAutomationStateStore. The default run-history implementation is MemoryAutomationRunHistory. The current automation layer does not claim to provide higher-level APIs such as:

automation.schedule(...)

automation.persist(...)

automation.worker(...)

trigger.retry(...)

trigger.schedule(...)

unless those capabilities are explicitly implemented elsewhere in BindAI. Automation run history is available through the AutomationRunHistory contract and its in-memory implementation, MemoryAutomationRunHistory. Persistent database-backed history is not supplied by the default implementation. Background execution is available through AutomationWorker, but it is process-local rather than distributed. One important implementation detail is that AutomationWorker stores submitted input on AutomationRun, but its current execution path calls:

definition.run()

without passing the stored input into the definition execution call. Documentation and applications should not assume that worker input is automatically provided to the automation target. Advanced event routing, persistent storage backends, distributed execution, automatic input propagation, and broader automation orchestration remain outside the current built-in implementation unless provided by an additional component.

Summary

BindAI Automation provides a lightweight foundation for stateful and event-driven automation. The current architecture separates automation definitions, execution state, historical records, triggers, and background execution:

AutomationDefinition
        |
        v
   AutomationRun
        |
        +----------------------+
        |                      |
        v                      v
AutomationStateStore   AutomationRunHistory
        |                      |
        v                      v
 Current Run State       Historical Runs

Event-driven automation uses:

Event Source
     |
     v
  EventBus
     |
     v
 EventTrigger
     |
     v
Application Target

Background execution uses:

AutomationDefinition
        |
        v
  AutomationWorker
        |
        v
   AutomationRun
        |
        +----------------------+
        |                      |
        v                      v
AutomationStateStore   AutomationRunHistory

The main public abstractions are:

from bindai_automation import (
    AutomationDefinition,
    AutomationRun,
    AutomationRunHistory,
    AutomationStateStore,
    AutomationWorker,
    MemoryAutomationRunHistory,
    MemoryAutomationStateStore,
    Trigger,
    EventTrigger,
    TriggerRegistry,
)

EventTrigger connects BindAI’s existing EventBus system to application-defined callable targets. AutomationRun represents an individual execution. AutomationStateStore manages current run state, while AutomationRunHistory provides a separate interface for historical records. AutomationWorker provides synchronous and background execution using an in-process thread pool. Its default state and history implementations are in-memory, and submitted input is stored on the run but is not automatically passed to AutomationDefinition.run(). The REST API can submit and inspect background automation runs through:

POST /api/v1/runs

GET /api/v1/runs/{run_id}

The current v0.1 architecture is intentionally lightweight. Persistent storage backends, distributed queues, coordinated workers, advanced event routing, automatic input propagation, and broader automation orchestration can be introduced in future releases without changing the basic separation between definitions, runs, state, history, triggers, and execution.

​Automation

​Automation Architecture

​Automation Package

​Automation Definitions

​Automation Runs

​Automation State

​In-Memory State Store

​Automation Run History

​In-Memory Run History

​Automation Worker

​Worker Configuration

​Synchronous Execution

​Background Submission

​Submit With Run

​Background Worker Model

​Worker Lifecycle

​Context Manager

​Run Execution

​Automation Input

​Automation Output

​Automation Failures

​Worker and Event Triggers

​Trigger

​Enabling and Disabling Triggers

​Event Triggers

​BindAI Event System

​Attaching an Event Trigger

​Detaching an Event Trigger

​Event Matching

​Event-Driven Automation

​Targets

​Trigger State

​Trigger Registry

​Registry Operations

​Automation and Agents

​Automation and Workflows

​Automation and Connections

​Automation and the REST API

​Automation State and the REST API

​Background Runs and Process Lifetime

​Horizontal Scaling

​Persistent State and History

​Error Handling

​Synchronous Event Processing

​Trigger Lifecycle

​Testing Automation

​Security Considerations

​Production Considerations

​Current Scope

​Automation

​Worker execution

​Event integration

​Registry support

​REST API integration

​Current Limitations

​Future Automation Capabilities

​Design Principles

​API Accuracy

​Summary

Automation

Automation Architecture

Automation Package

Automation Definitions

Automation Runs

Automation State

In-Memory State Store

Automation Run History

In-Memory Run History

Automation Worker

Worker Configuration

Synchronous Execution

Background Submission

Submit With Run

Background Worker Model

Worker Lifecycle

Context Manager

Run Execution

Automation Input

Automation Output

Automation Failures

Worker and Event Triggers

Trigger

Enabling and Disabling Triggers

Event Triggers

BindAI Event System

Attaching an Event Trigger

Detaching an Event Trigger

Event Matching

Event-Driven Automation

Targets

Trigger State

Trigger Registry

Registry Operations

Automation and Agents

Automation and Workflows

Automation and Connections

Automation and the REST API

Automation State and the REST API

Background Runs and Process Lifetime

Horizontal Scaling

Persistent State and History

Error Handling

Synchronous Event Processing

Trigger Lifecycle

Testing Automation

Security Considerations

Production Considerations

Current Scope

Automation

Worker execution

Event integration

Registry support

REST API integration

Current Limitations

Future Automation Capabilities

Design Principles

API Accuracy

Summary